1. 什么是 MCP Inspector？ #

MCP Inspector 是一个用于测试和调试 MCP 服务器的图形化工具。你可以用它：

• 连接本地或远程 MCP 服务器
• 查看并调用服务器提供的工具、资源、提示
• 观察请求与响应，排查协议或实现问题

通俗理解	说明
像 Postman 之于 API	Inspector 之于 MCP 服务器，用来手动发请求、看结果
无需写客户端代码	打开 Inspector 即可连接服务器，快速验证功能
适合开发调试	开发 MCP 服务器时，用 Inspector 边改边测

2. 本章你将学到 #

• 如何安装和启动 MCP Inspector
• 如何连接 npm、PyPI、本地开发的服务器
• Inspector 各功能模块的用途
• 推荐的开发与测试流程

3. 快速开始 #

3.1 一行命令启动 #

Inspector 通过 npx 运行，无需单独安装：

npx @modelcontextprotocol/inspector <command>

<command> 是启动 MCP 服务器的方式，Inspector 会接管该进程并与服务器通信。

3.2 连接不同类型的服务器 #

服务器来源	命令格式	示例
npm 包	npx -y @modelcontextprotocol/inspector npx <包名> <参数>	见下方
PyPI 包	npx @modelcontextprotocol/inspector uvx <包名> <参数>	见下方
本地项目	npx @modelcontextprotocol/inspector uv --directory <路径> run <包名> <参数>	见下方

示例 1：连接 npm 文件系统服务器 #

npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/username/Desktop

• npx -y：自动确认安装，不交互
• @modelcontextprotocol/server-filesystem：npm 包名
• /Users/username/Desktop：传给服务器的参数（要访问的目录）

示例 2：连接 PyPI Git 服务器 #

npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

• uvx：用 uv 运行 PyPI 包（类似 npx 之于 npm）
• mcp-server-git：PyPI 包名
• --repository：传给服务器的参数

示例 3：连接本地开发的服务器 #

假设你在 path/to/weather-server 开发了一个天气 MCP 服务器：

npx @modelcontextprotocol/inspector uv --directory path/to/weather-server run weather-server.py

• --directory：项目根目录
• run：uv 子命令
• weather-server：包名（来自 pyproject.toml 的 [project].name）

提示：具体命令以项目 README 为准，不同包参数可能不同。

4. 界面与功能概览 #

启动后，Inspector 会打开一个 Web 界面，主要包含以下区域：

4.1 服务器连接面板 #

功能	说明
选择传输方式	支持 stdio、Streamable HTTP 等，根据服务器类型选择
自定义参数	本地服务器可配置命令行参数、环境变量
连接 / 断开	连接后 Inspector 与服务器建立会话

4.2 工具选项卡 #

功能	说明
工具列表	显示服务器暴露的所有工具（名称、描述）
调用测试	输入参数后点击执行，查看返回结果
结果展示	显示工具执行结果，便于排查错误

典型用法：开发 get_forecast 工具时，在 Inspector 中传入 latitude=37.5, longitude=-122，检查返回的 JSON 是否符合预期。

4.3 资源选项卡 #

功能	说明
资源列表	列出所有可用资源（URI、MIME 类型、描述）
内容预览	点击资源可查看内容
订阅测试	测试资源变更通知

4.4 提示选项卡 #

功能	说明
提示模板	显示服务器提供的提示模板
参数输入	为提示填入参数，预览生成的消息
消息预览	查看最终发给 AI 的消息内容

4.5 通知面板 #

功能	说明
服务器日志	显示服务器输出的日志
通知消息	显示 notifications/ 等通知，便于调试事件流

5. 推荐开发流程 #

5.1 初次连接 #

1. 用 Inspector 启动你的服务器（见 3.2 连接不同类型的服务器）
2. 确认连接成功，检查能力协商是否正常
3. 在工具选项卡中查看工具列表是否完整

5.2 迭代开发 #

1. 修改服务器代码
2. 重新构建（如 uv build、npm run build）
3. 在 Inspector 中断开并重新连接
4. 测试修改过的工具、资源或提示
5. 在通知面板中观察日志和错误

5.3 边界与异常测试 #

测试类型	示例
无效输入	传入空字符串、负数、超长文本
缺失参数	不填必填参数，检查错误提示
并发调用	同时发起多个工具调用
错误处理	模拟网络失败、超时，验证错误响应格式

6. 常见问题 #

问题	可能原因	建议
连接失败	命令或参数错误	对照 README 检查命令格式；确认路径、包名正确
工具列表为空	服务器未正确暴露工具	检查 `@mcp.tool()` 等装饰器；查看服务器日志
执行工具报错	参数格式不符或服务器内部异常	查看 Inspector 中的错误详情；在服务器端加日志
本地项目连不上	--directory 或 run 参数不对	确认 pyproject.toml 或 package.json 配置；用 uv run 本地先跑通